home *** CD-ROM | disk | FTP | other *** search
/ The Very Best of Atari Inside / The Very Best of Atari Inside 1.iso / mint / mintman / filesys.doc < prev    next >
Text File  |  1991-11-02  |  28KB  |  588 lines
  1. MiNT File Systems
  2.  
  3. MiNT allows loadable file systems, which means that it should be quite
  4. easy to implement networked file systems, dynamically re-sizable ram
  5. disks, or other nifty things (for example, Stephen Henson's minix.xfs
  6. file system allows access to Minix partitions from TOS). Writing
  7. these is not difficult, but there are a lot of data structures that
  8. must be understood first:
  9.  
  10. File Cookies
  11.  
  12. Files and directories are represented in the kernel by "cookies".
  13. The contents of the cookie are mostly file system dependent, i.e. the
  14. kernel interprets only the "fs" and "dev" field of the cookie, and the
  15. contents of the other fields may be used by a file system as it sees fit.
  16.  
  17. A file cookie has the following structure:
  18.  
  19. typedef struct f_cookie {
  20.     FILESYS *fs;        /* file system that knows about this cookie */
  21.     ushort    dev;        /* device info (e.g. Rwabs device number) */
  22.     ushort    aux;        /* extra data that the file system may want */
  23.     long    index;        /* this+dev uniquely identifies a file */
  24. } fcookie;
  25.  
  26. (The "FILESYS" data type is defined below.)
  27.  
  28. File System Structure
  29.  
  30. This is the structure that tells the kernel about the file system,
  31. and gives the entry points for routines which the kernel can call in order
  32. to manipulate files and directories. Note that actual input/output
  33. operations are performed by a device driver; most file systems have just
  34. one associated device driver, but some may have more. See the section on
  35. device drivers for more information on these.
  36.  
  37. Unless otherwise specified, all of the functions should return 0 for
  38. success and an appropriate (long negative) error code for failure.
  39.  
  40. typedef struct filesys {
  41.     struct    filesys    *next;
  42.  
  43. This is a link to the next file system in the kernel's list. It will be
  44. filled in by the kernel; the file system should leave it as NULL.
  45.  
  46.     long    fsflags;
  47. These flags give some information about the file system. Currently, three
  48. flags are defined:
  49.  
  50. #define FS_KNOPARSE     0x01    /* kernel shouldn't do parsing */
  51. #define FS_CASESENSITIVE 0x02    /* file names are case sensitive */
  52. #define FS_NOXBIT     0x04    /* if a file can be read, it can be executed */
  53.  
  54. Other bits may be defined in future releases of MiNT; for now all other
  55. bits in this flag should be 0.
  56.  
  57.     long    (*root) P_((int drv, fcookie *fc));
  58. This is the entry point for a routine to find a file cookie for the root
  59. directory of BIOS device "drv" (an integer in the range 0-31 inclusive).
  60. This function is called by the kernel when initializing a drive; the kernel
  61. will query each file system in turn for a file cookie representing the
  62. root directory of the drive. If the file system recognizes the data on
  63. the drive as being valid, it should fill in the cookie pointed to by "fc"
  64. and return 0. Otherwise, it should return a negative error code (EDRIVE is
  65. a good choice) to indicate that the drive must belong to another file
  66. system. Note that this function is called at boot up time and also at any
  67. time when media change is detected on a drive.
  68.  
  69.     long    (*lookup) P_((fcookie *dir, char *name, fcookie *fc));
  70. Translate a file name into a cookie. "dir" is the cookie for a directory,
  71. returned by a previous call to (*lookup) or (*root). "name" is either the
  72. name of a file in that directory (if fsflags & FS_KNOPARSE == 0) or a path
  73. name relative to that directory (if fsflags & FS_KNOPARSE == FS_KNOPARSE).
  74. If the file is not found, an appropriate error code (like EFILNF) should be
  75. returned. If the file is found, the cookie "*fc" should be filled in with
  76. appropriate data, and either 0 or EMOUNT returned. EMOUNT should be returned
  77. only if "name" is ".." and "dir" represents the root directory of a drive;
  78. 0 should be returned otherwise. Note that a lookup call with a null name
  79. or with "." should always succeed and return a cookie representing the
  80. directory itself. Also note that symbolic links should *never* be followed.
  81.  
  82.     long    (*creat) P_((fcookie *dir, char *name, unsigned mode,
  83.                 int attrib, fcookie *fc)
  84. Create a new file named "name" in the directory whose cookie is "dir".
  85. "mode" gives the file's type and access permissions, as follows:
  86.     /* file types */
  87.     #define S_IFMT    0170000        /* mask to select file type */
  88.     #define S_IFCHR    0020000        /* BIOS special file */
  89.     #define S_IFDIR    0040000        /* directory file */
  90.     #define S_IFREG 0100000        /* regular file */
  91.     #define S_IFIFO 0120000        /* FIFO */
  92.     #define S_IMEM    0140000        /* memory region or process */
  93.     #define S_IFLNK    0160000        /* symbolic link */
  94.  
  95.     /* file access modes for user, group, and other*/
  96.     #define S_IRUSR    0400
  97.     #define S_IWUSR 0200
  98.     #define S_IXUSR 0100
  99.     #define S_IRGRP 0040
  100.     #define S_IWGRP    0020
  101.     #define S_IXGRP    0010
  102.     #define S_IROTH    0004
  103.     #define S_IWOTH    0002
  104.     #define S_IXOTH    0001
  105.  
  106. "attrib" gives the standard TOS attribute byte.
  107.  
  108. The kernel will make the "creat" call only after using "lookup" in an attempt
  109. to find the file. The file system should create the file (if possible) and
  110. set the cookie pointed to by "fc" to represent the newly created file.
  111. If an error of any sort occurs, an appropriate error number is returned,
  112. otherwise 0 is returned.
  113.  
  114.     DEVDRV *(*getdev) P_((fcookie *fc, long *devspecial))
  115. Get the device driver which should be used to do i/o on the file whose
  116. cookie is "fc". If an error occurs, a NULL pointer should be returned
  117. and an error code placed in the long pointed to by "devspecial"; otherwise,
  118. "devspecial" should be set to a device-driver specific value which will
  119. be placed by the kernel in the "devinfo" field of the FILEPTR structure
  120. passed to the device driver's open routine. (The interpretation of
  121. this value is a matter for the file system and the device driver, the
  122. kernel doesn't care.)
  123.  
  124. If the call to (*getdev) succeeds, a pointer to a device driver structure
  125. (see below) is returned; if it fails, a NULL pointer should be returned and
  126. an appropriate error number placed in *devspecial.
  127.  
  128.     long    (*getxattr) P_((fcookie *file, XATTR *xattr));
  129. Get a file's attributes. The XATTR structure pointed to by "xattr" should
  130. be filled in with the data for the file or directory represented by
  131. the cookie "*file" should be filled in, and 0 returned. If a fatal
  132. error occurs (e.g. media change) an error code is returned instead.
  133. The XATTR structure is defined as follows:
  134.  
  135. /* structure for getxattr */
  136.     typedef struct xattr {
  137.     ushort    mode;
  138. file types and permissions; same as the mode passed to (*creat) (see above)
  139.     long    index;
  140. file index; this should be a unique number for the file, so that no
  141. two files on the same physical drive could have the same index
  142.     ushort    dev;
  143. physical device on which the file is located; normally set to fc->dev
  144.     ushort    reserved1;
  145. set to 0
  146.     ushort    nlink;
  147. number of hard links to the file; normally 1
  148.     ushort    uid;
  149. a number representing the user that owns the file
  150.     ushort    gid;
  151. the group ownership of the file
  152.     long    size;
  153. length of the file, in bytes
  154.     short    mtime, mdate;
  155. last modification time and date of the file, in standard GEMDOS format
  156.     short    atime, adate;
  157. last access time and date for the file, in standard GEMDOS format; if the
  158. file system does not keep separate record of these, they should be the same
  159. as mtime and mdate
  160.     short    ctime, cdate;
  161. file creation time and date, in standard GEMDOS format; if the file system
  162. does not keep separate record of these, they should be the same as mtime
  163. and mdate
  164.     short    attr;
  165. TOS attribute byte for the file in the lower 8 bits; the upper 8 should
  166. be 0
  167.     short    reserved2;
  168. reserved, set to 0
  169.     long    reserved3[2];
  170. reserved, set both long words to 0
  171.     } XATTR;
  172.  
  173.     long    (*chattr) P_((fcookie *file, int attr));
  174. Change the TOS attributes of the file whose cookie is "*file" to "attr".
  175. Only the lower 8 bits of "attr" should be considered significant, for now.
  176. The kernel will not allow changes if the file's current attributes include
  177. the FA_DIR bit or the FA_LABEL bit. Not all filesystems will support all
  178. TOS attribute bits, but FA_RDONLY should probably be supported if possible;
  179. usually setting the FA_RDONLY bit should be equivalent to turning off all
  180. write permissions to the file.
  181.  
  182.     long    (*chown) P_((fcookie *file, int uid, int gid));
  183. Change a file's user and group ownership to "uid" and "gid" respectively.
  184. The kernel checks access permissions before making this call, so file
  185. systems do not have to. If the file system does not support a concept
  186. of ownership, or does not allow changes to ownership, it should return
  187. EINVFN.
  188.  
  189.     long    (*chmode) P_((fcookie *file, unsigned mode));
  190. Change a file's access permissions. "mode" is similar to the field in
  191. the XATTR structure or the value passed to creat, except that _only_
  192. the permission bits are significant; (mode & S_IFMT) will always be 0.
  193. In the event that the file system supports only a subset of permissions
  194. (e.g. the TOS file system can only control write access to the file)
  195. then it may consider only the relevant bits of "mode".
  196.  
  197.     long    (*mkdir) P_((fcookie *dir, char *name, unsigned mode));
  198. Make a new subdirectory called "name" of the directory whose cookie is
  199. "*dir". The new directory should have the file permissions given by
  200. "mode & ~S_IFMT". Note that the file system should do all appropriate
  201. initializations for the new directory, including making entries for
  202. "." and "..".
  203.  
  204.     long    (*rmdir) P_((fcookie *dir, char *name));
  205. Delete the subdirectory called "name" of the directory whose cookie is
  206. "*dir".
  207.  
  208.     long    (*remove) P_((fcookie *dir, char *name));
  209. Delete the file called "name" in the directory "*dir". This call should
  210. act like the Unix "unlink" call, i.e. if the file has more than 1 hard
  211. link to it, only this particular link to the file should be removed and
  212. the file contents should not be affected.
  213.  
  214.     long    (*getname) P_((fcookie *relto, fcookie *dir, char *pathname));
  215. This is analogous to the "getcwd()" operation in Unix. It should get the name
  216. of the directory whose cookie is "*dir", expressed as a path relative
  217. to the directory whose cookie is "*relto"; normally, this is the root
  218. directory, but the file system should not assume this. The resulting path
  219. is placed in the array pointed to by *pathname, which is PATH_MAX bytes
  220. long.
  221.  
  222. Example: if "*relto" is the directory "\FOO", and "*dir" is the directory
  223. "\FOO\BAR\SUB", then after the call "pathname" should contain "\BAR\SUB".
  224.  
  225.     long    (*rename) P_((fcookie *olddir, char *oldname,
  226.                 fcookie *newdir, char *newname));
  227. Rename the file with name "oldname" contained in the directory whose cookie
  228. is "*olddir" to the name "newname" in the directory whose cookie is "*newdir".
  229.  
  230.     long    (*opendir) P_((DIR *dirh, int tosflag));
  231. Open a directory for reading. "dirh" is a pointer to a structure as defined
  232. below; the file cookie for the directory being opened may be found there.
  233. "tosflag" is a copy of "dirh->flags" and is in a sense redundant. The
  234. file system should initialize the "fsstuff" and "index" fields of "*dirh"
  235. to whatever it needs for carrying out a successful search.
  236.  
  237. /* structure for opendir/readdir/closedir */
  238. typedef struct dirstruct {
  239.     fcookie fc;        /* cookie for this directory */
  240.     ushort    index;        /* index of the current entry */
  241.     ushort    flags;        /* flags (e.g. tos or not) */
  242. #define TOS_SEARCH    0x01
  243. /* if TOS_SEARCH is set, this call originated from a TOS Fsfirst() system
  244.  * call -- if possible, the returned names should be acceptable to a
  245.  * "naive" TOS program
  246.  */
  247.     char    fsstuff[60];    /* anything else the file system wants */
  248. } DIR;
  249.  
  250.     long    (*readdir) P_((DIR *dirh, char *name, int namelen, fcookie *fc));
  251. Read the next name from the directory whose DIR structure (see above)
  252. is "*dirh". The name should be copied into "name" (if dirh->flags & TOS_SEARCH
  253. is nonzero) or "name+4" if dirh->flags & TOS_SEARCH is 0; in the latter case,
  254. the first 4 bytes of "name" should be a unique index for the file. "namelen"
  255. is the total size of the buffer for "name"; if the next file name (plus index,
  256. if appopriate, and including the trailing 0) is too long for the buffer, as
  257. much of it as will fit should be copied in and ENAMETOOLONG returned. If no
  258. more file names remain unread in the directory, ENMFIL should be returned
  259. and "name" left unchanged. Otherwise, 0 should be returned.
  260.  
  261.     long    (*rewinddir) P_((DIR *dirh));
  262. Reset the file system specific fields of "*dirh" so that the next call to
  263. "readdir" on this directory will return the first file name in the directory.
  264.  
  265.     long    (*closedir) P_((DIR *dirh));
  266. Called by the kernel when the directory "*dirh" is not going to be searched
  267. any more; if the file system needs to clean up any structures or free memory
  268. allocated for the search it can do so here.
  269.  
  270.     long    (*pathconf) P_((fcookie *dir, int which));
  271. Get path configuration information for the directory whose cookie is
  272. "*dir". "which" indicates what kind of information should be returned,
  273. as follows:
  274.  
  275. /* The requests for pathconf() */
  276. #define DP_IOPEN    0    /* internal limit on # of open files */
  277. #define DP_MAXLINKS    1    /* max number of hard links to a file */
  278. #define DP_PATHMAX    2    /* max path name length */
  279. #define DP_NAMEMAX    3    /* max length of an individual file name */
  280. #define DP_ATOMIC    4    /* # of bytes that can be written atomically */
  281. #define DP_TRUNC    5    /* file name truncation behavior */
  282. /* possible return values for DP_TRUNC */
  283. #    define    DP_NOTRUNC    0    /* long names cause an error */
  284. #    define    DP_AUTOTRUNC    1    /* long names are truncated */
  285. #    define    DP_DOSTRUNC    2    /* DOS 8+3 rules are used */
  286.  
  287. #define DP_MAXREQ    5    /* highest legal request */
  288. /* Dpathconf and Sysconf return this when a value is not limited
  289.    (or is limited only by available memory) */
  290. #define UNLIMITED    0x7fffffffL
  291.  
  292.     long    (*dfree) P_((fcookie *dir, long *buf));
  293. Determine bytes used and free on the disk that the directory whose cookie
  294. is "*dir" is contained on. "buf" points to the same kind of buffer that
  295. the "Dfree" system call uses; see the documentation for that call.
  296.  
  297.     long    (*writelabel) P_((fcookie *dir, char *name));
  298. Create a volume label with the indicated name on the drive which contains
  299. the directory whose cookie is "*dir". If a label already exists, the file
  300. system may either fail the call with EACCDN or re-write the label. If the
  301. file system doesn't support the notion of labels, it should return EINVFN.
  302.  
  303.     long    (*readlabel) P_((fcookie *dir, char *name, int namelen));
  304. Read the volume label for the disk which contains the directory whose cookie
  305. is "*dir" into the buffer "name", which is "namelen" bytes long. If the
  306. volume label (including trailing 0) won't fit, return ENAMETOOLONG.
  307.  
  308.     long    (*symlink) P_((fcookie *dir, char *name, char *to));
  309. Create a symbolic link called "name" in the directory whose cookie is
  310. "*dir". The link should contain the 0-terminated string "to". If the file
  311. system doesn't support symbolic links, it should return EINVFN.
  312.  
  313.     long    (*readlink) P_((fcookie *file, char *buf, int buflen));
  314. Read the contents of the symbolic link whose cookie is "*file" into the
  315. buffer "buf", which is "buflen" bytes long. If the contents (including the
  316. trailing 0) won't fit, return ENAMETOOLONG; if the file system doesn't
  317. do symbolic links, return EINVFN.
  318.  
  319.     long    (*hardlink) P_((fcookie *fromdir, char *fromname,
  320.                 fcookie *todir, char *toname));
  321. Create a hard link called "toname" in the directory whose cookie is
  322. "*todir" for the file named "fromname" in the directory whose cookie is
  323. "*fromdir". If the file system doesn't do hard links, return EINVFN.
  324.  
  325.     long    (*fscntl) P_((fcookie *dir, char *name, int cmd, long arg));
  326. Perform an operation on the file whose name is "name", in the directory with
  327. cookie "*dir". "cmd" and "arg" specify the operation, and are file system
  328. specific. See the documentation for Dcntl() for more details. Most file
  329. systems will just return EINVFN for any values of "cmd" and "arg"; this call
  330. is here so that you can provide users with a way to manipulate various special
  331. features of your file system.
  332.  
  333.     long    (*dskchng) P_((int drv));
  334. Check for media change. "drv" is the BIOS device number on which the
  335. kernel thinks there has been a change. This function is called only
  336. when the kernel detects what the BIOS claims is a definite disk change
  337. (i.e. Mediach returning 2 or Mediach returning 1 and Rwabs returning -14).
  338. This may be the result of a program trying to force a media change; if the
  339. file system agrees that a change has occured, it should perform any
  340. appropriate actions (e.g. invalidating buffers) and return 1; the kernel
  341. will then invalidate any open files or directories on the device and
  342. re-check what file system the device belongs  If no change, in fact, occured,
  343. a 0 should be returned to tell the kernel not to worry.
  344.  
  345.     long    zero;
  346. A long word present to allow for future expansion; this must always be set
  347. to 0 by file systems (for now).
  348. } FILESYS;
  349.  
  350. typedef struct fileptr {
  351.     short    links;        /* number of copies of this descriptor */
  352.     ushort    flags;        /* file open mode and other file flags */
  353. #define O_RWMODE      0x03    /* isolates file read/write mode */
  354. #    define O_RDONLY    0x00
  355. #    define O_WRONLY    0x01
  356. #    define O_RDWR    0x02
  357. #    define O_EXEC    0x03    /* execute file; used by kernel only */
  358.  
  359. #define O_SHMODE    0x70    /* isolates file sharing mode */
  360. #    define O_COMPAT    0x00    /* compatibility mode */
  361. #    define O_DENYRW    0x10    /* deny both read and write access */
  362. #    define O_DENYW    0x20    /* deny write access to others */
  363. #    define O_DENYR    0x30    /* deny read access to others */
  364. #    define O_DENYNONE 0x40    /* don't deny any access to others */
  365.  
  366. #define O_NOINHERIT    0x80    /* this is currently ignored by MiNT */
  367. #define O_NDELAY    0x100    /* don't block for i/o on this file */
  368. #define O_CREAT        0x200    /* create file if it doesn't exist */
  369. #define O_TRUNC        0x400    /* truncate file to 0 bytes if it does exist */
  370. #define O_EXCL        0x800    /* fail open if file exists */
  371. #define O_BIOS        0x2000    /* file is a terminal */
  372. #define O_HEAD        0x4000    /* file is a pseudo-terminal "master" */
  373.  
  374. The "flags" is constructed by or'ing together exactly one read/write mode,
  375. one sharing mode, and any number of the other bits. Device drivers can
  376. ignore the O_CREAT flag, since file creation is handled by the kernel.
  377. The O_TRUNC flag, however, should be respected; the file should be
  378. truncated to 0 length if this flag is set.
  379.  
  380.     long    pos;        /* position in file */
  381. The kernel doesn't actually use this field, except to initialize it to
  382. 0; it is recommended that device drivers that allow seeking should use it
  383. to store the current position in the file (relative to the start of
  384. the file). Other device drivers may use it for other purposes.
  385.     long    devinfo;    /* device driver specific info */
  386. This field is passed back to the kernel from the file system from the
  387. "getdev" call; its interpretation is file system specific, except that
  388. if this is a terminal device (i.e. the O_BIOS bit is set in "flags") then
  389. this must be a pointer to a struct tty for this terminal.
  390.     fcookie    fc;        /* file system cookie for this file */
  391. This is the cookie for the file, as returned by the file system "lookup"
  392. function during opening of the file.
  393.     struct devdrv *dev; /* device driver that knows how to deal with this */
  394. This is the device driver returned by the "getdev" call.
  395.     struct fileptr *next; /* link to next fileptr for this file */
  396. This field may be used by device drivers to keep a linked list of file
  397. pointers that refer to the same physical file, for example, in order to
  398. implement file sharing or locking code.
  399. } FILEPTR;
  400.  
  401. typedef struct devdrv {
  402.     long (*open)    P_((FILEPTR *f));
  403. This routine is called by the kernel during a file "open", after it has
  404. constructed a FILEPTR for the file being opened and determined the device
  405. driver. The device driver should check the contents of the FILEPTR and
  406. make any changes or initializations necessary. If for some reason the open
  407. call should be failed, an appropriate error code must be returned (in which
  408. case the kernel will free the FILEPTR structure automatically). For example,
  409. if the file sharing mode in f->flags is not compatible with the sharing
  410. mode of another open FILEPTR referring to the same physical file, EACCDN should
  411. be returned.
  412.  
  413.     long (*write)    P_((FILEPTR *f, char *buf, long bytes));
  414. Write "bytes" bytes from the buffer pointed to by "buf" to the file with
  415. FILEPTR "f". Return the number of bytes actually written.
  416.  
  417.     long (*read)    P_((FILEPTR *f, char *buf, long bytes));
  418. Read "bytes" bytes from the file with FILEPTR "f" into the buffer pointed
  419. to by "buf". Return the number of bytes actually read.
  420.  
  421.     long (*lseek)    P_((FILEPTR *f, long where, int whence));
  422. Seek to a new position in the file. "where" is the new position; "whence"
  423. says what "where" is relative to, as follows:
  424. /* lseek() origins */
  425. #define    SEEK_SET    0        /* from beginning of file */
  426. #define    SEEK_CUR    1        /* from current location */
  427. #define    SEEK_END    2        /* from end of file */
  428.  
  429.     long (*ioctl)    P_((FILEPTR *f, int mode, void *buf));
  430. Perform a device specific function. "mode" is the function desired. All devices
  431. should support the FIONREAD and FIONWRITE functions.
  432.  
  433.     long (*datime)    P_((FILEPTR *f, short *timeptr, int rwflag));
  434. Get or set the date/time of the file. "timeptr" is a pointer to two words,
  435. the first of which is the time and the second of which is the date.
  436. If "rwflag" is 0, the time and date of the file should be placed into timeptr.
  437. If "rwflag" is nonzero, then the time and date of the file should be set to
  438. agree with the time and date pointed to by timeptr.
  439.  
  440.     long (*close)    P_((FILEPTR *f));
  441. Called every time an open file is closed. Note that the file is "really"
  442. being closed if f->links == 0, and almost all device drivers will only
  443. want to do any processing if this is the case; otherwise, the FILEPTR is
  444. still being used by some process.
  445.  
  446.     long (*select)    P_((FILEPTR *f, long proc, int mode));
  447. Called by Fselect() when "f" is one of the file handles a user has chosen to
  448. do a select on. If mode is O_RDONLY, the select is for reading; if
  449. it is O_WRONLY, it is for writing (if it is for both reading and writing,
  450. the function will be called twice). The select function should return
  451. 1 if the device is ready for reading or writing (i.e. if a read or write
  452. call to the device will not block); otherwise, it should take whatever
  453. steps are necessary to arrange to wake up the process whose PROC structure is
  454. pointed to by "proc" when the appropriate I/O on the device becomes possible.
  455. Normally, this will be done by calling the "wakeselect" function as passed
  456. by the kernel in "struct kerinfo" with "proc" as its parameter.
  457.  
  458.     void (*unselect) P_((FILEPTR *f, long proc, int mode));
  459. Called when the kernel is returning from an Fselect that had previously
  460. selected this file or device; the device driver should no longer notify
  461. "proc" when I/O is possible for this file or device. "mode" is the same
  462. mode as was passed to the select() function (see above), i.e. either
  463. O_RDONLY or O_WRONLY; as with select(), unselect() will be called twice
  464. if both input and output were selected for.
  465. } DEVDRV;
  466.  
  467.  
  468.  
  469. How the File System Is Booted
  470.  
  471. A loadable file system is an ordinary TOS executable file with an
  472. extension of ".xfs". MiNT searches its current directory (normally the
  473. root directory of the boot disk) when it is starting for all such
  474. files, and loads them with Pexec mode 3. It then does a jump to
  475. subroutine call to the first instruction of the loaded program,
  476. passing on the stack a pointer to a structure of type "struct kerinfo"
  477. (see below) which describes the version of MiNT and provides entry points
  478. for various utility functions.
  479.  
  480. The file system should *not* set up a stack or shrink its basepage
  481. (so the ordinary C startup code is not necessary). MiNT has already provided
  482. a stack of about 8K or so, and has shrunk the basepage to the bare minimum.
  483. What the file system initialization code *should* do is to check that an
  484. appropriate version of MiNT is running and to otherwise check the system
  485. configuration to see if it is appropriate for the file system driver.
  486. If so, a pointer to a FILESYS structure should be returned; if not, a NULL
  487. pointer should be returned.
  488.  
  489. Note that it is not necessary to actually check during initialization for
  490. the presence of disks with the appropriate file system types; MiNT will
  491. call the file system "root" function for each drive in the system, and such
  492. checks should be done there.
  493.  
  494. If the file system driver wishes to add new (pseudo) drives to the system,
  495. it should update the drive configuration variable stored at 0x4c2 to
  496. reflect the presence of these new drives.
  497.  
  498. File system drivers should *not* make any calls to the BIOS or GEMDOS
  499. directly; all such calls should be made through the vectors provided by
  500. the kernel as part of the struct kerinfo.
  501.  
  502. /*
  503.  * this is the structure passed to loaded file systems to tell them
  504.  * about the kernel
  505.  */
  506.  
  507. typedef long (*Func)();
  508.  
  509. struct kerinfo {
  510.     short    maj_version;    /* kernel version number */
  511.     short    min_version;    /* minor kernel version number */
  512.     ushort    default_mode;    /* default file access permissions */
  513.     short    reserved1;    /* room for expansion */
  514.  
  515. /* OS functions */
  516.     Func    *bios_tab;    /* pointer to the BIOS entry points */
  517.     Func    *dos_tab;    /* pointer to the GEMDOS entry points */
  518.  
  519. /* media change vector: call this if a device driver detects a disk
  520.  * change during a read or write operation. The parameter is the BIOS device
  521.  * number of the disk that changed.
  522.  */
  523.     void    (*drvchng) P_((unsigned));
  524.  
  525. /* Debugging stuff */
  526.     void    (*trace) P_((char *, ...));    /* informational messages */
  527.     void    (*debug) P_((char *, ...));    /* error messages */
  528.     void    (*alert) P_((char *, ...));    /* really serious errors */
  529.     void    (*fatal) P_((char *, ...));    /* fatal errors */
  530.  
  531. /* memory allocation functions */
  532. /* kmalloc and kfree should be used for most purposes, and act like malloc
  533.  * and free respectively. umalloc and ufree may be used to allocate/free memory
  534.  * that is attached to the current process, and which is freed automatically
  535.  * when the process exits; this is generally not of much use to a file system
  536.  * driver
  537.  */
  538.     void *    (*kmalloc) P_((long));
  539.     void    (*kfree) P_((void *));
  540.     void *    (*umalloc) P_((long));
  541.     void    (*ufree) P_((void *));
  542.  
  543. /* utility functions for string manipulation */
  544.     int    (*strnicmp) P_((char *, char *, int));
  545.     int    (*stricmp) P_((char *, char *));
  546.     char *    (*strlwr) P_((char *));
  547.     char *    (*strupr) P_((char *));
  548.     int    (*sprintf) P_((char *, const char *, ...));
  549.  
  550. /* utility functions for manipulating time */
  551. /* convert "ms" milliseconds into a DOS time (in td[0]) and date (in td[1]) */
  552.     void    (*millis_time) P_((unsigned long ms, short *td));
  553.  
  554. /* convert a DOS style time and date into a Unix style time; returns the
  555.  * Unix time
  556.  */
  557.     long    (*unixtim) P_((unsigned time, unsigned date));
  558.  
  559. /* convert a Unix time into a DOS time (in the high word of the returned
  560.  * value) and date (in the low word)
  561.  */
  562.     long    (*dostim) P_((long));
  563.  
  564. /* utility functions for dealing with pauses */
  565. /* go to sleep temporarily for at least "n" milliseconds */
  566.     void    (*nap) P_((unsigned n));
  567.  
  568. /* wait on system queue "que" until a condition occurs */
  569.     void    (*sleep) P_((int que, long cond));
  570. /* wake all processes on queue "que" that are waiting for condition "cond" */
  571.     void    (*wake) P_((int que, long cond));
  572.  
  573. /* wake a process that is doing a select(); "param" should be the process
  574.  * code passed to select()
  575.  */
  576.     void    (*wakeselect) P_((long param));
  577.  
  578. /* file system utility functions */
  579. /* "list" is a list of open files; "f" is a new file that is being opened.
  580.  * If the file sharing mode of "f" conflicts with any of the FILEPTRs
  581.  * in the list, then this returns 1, otherwise 0.
  582.  */
  583.     int    (*denyshare) P_((FILEPTR *list, FILEPTR *f));
  584.  
  585. /* reserved for future use */
  586.     long    res2[10];
  587. };
  588.